package com.linkgie.galaxyframework.utils;

import java.util.concurrent.Callable;

/**
 * 执行上下文的处理接口；
 * <p>
 * 用于定义执行上下文的开始和结束时的处理逻辑；
 * <p>
 * 方法 {@link ExecutionContextHandle#init() } 执行上下文的初始化操作；
 * <br>
 * 方法 {@link ExecutionContextHandle#clean() } 执行上下文的清理操作；
 * <p>
 * 注：
 * 此接口的初始化和清理方法有意被设计为无参数函数，与调用目标({@link Runnable} 或
 * {@link Callable})隔离，目的是避免在上下文初始化或清理过程中错误地执行调用目标；
 * <br>
 * 在代码设计上，对于与调用目标的状态有关的上下文处理逻辑，更合理的做法是放在调用目标的执行函数中进行处理。
 */
public interface ExecutionContextHandle<T> {

    /**
     * 初始化上下文；
     * <p>
     * 在上下文调用目标执行之前先执行( {@link ExecutionContext#run(Runnable) } 或
     * {@link ExecutionContext#call(Runnable) })
     * 
     * <p>
     * 初始化过程如果对外抛出异常，将会引发 {@link ContextException} 异常，中断对调用目标的执行，并且不会执行清理函数 {@link #clean()} ；
     * <br>
     * 因此，实现者应确保在初始化上下文中对异常的安全处理，确保在异常发生时对上下文的变更可以恢复到正确的状态；
     * 
     * @return 返回表示上下文状态的对象，或者 null ；返回值将会被传递清理函数 ({@link #clean(Object)})
     */
    T init();

    /**
     * 清理上下文；
     * <p>
     * 在上下文调用目标执行之后执行 ({@link ExecutionContext#run(Runnable) } 或
     * {@link ExecutionContext#call(Runnable) } )；
     * <p>
     * 无论调用目标是否异常返回，清理函数都会被执行；
     * <br>
     * 实现者应避免在清理函数中引发异常，因为打乱调用目标返回后的执行过程；
     * 
    * @param context
    */
    void clean(T context);

}